Node / ReticulumProjects / MeshChatX.git / files / docs / en / architecture.md

Displaying Raw • View rendered • Download

Tc9d1d9# Architecture and design

MeshChatX is a fork of Reticulum MeshChat with LXST telephony, RRC relay chat, Nomad tooling, plugins, and a SQL backend without Peewee. The goals below shaped how the codebase is organized.

Tc9d1d9## Design goals

Tff7b72- Keep a local-first runtime that works on desktop, mobile, containers, and single-board computers.

Tff7b72- Preserve Reticulum and LXMF semantics while improving usability and operational tooling.

Tff7b72- Support multiple identities in one process without cross-identity data leakage.

Tff7b72- Keep the Python backend and Vue frontend independently testable.

Tff7b72- Run in constrained environments with predictable SQLite behaviour.

Mesh features should follow Reticulum’s post-IP design patterns (portable identity hashes, announces, store-and-forward, transport-agnostic APIs, scarce payloads). Agent and contributor gates live in Ta5d6ff`.agents/conventions/reticulum-zen.md` and Ta5d6ff`.agents/skills/reticulum-design-gates/SKILL.md`, derived from the [Tff7b72Zen of Reticulum](Te6edf3https://reticulum.network/manual/zen.html).

Tc9d1d9## Process overview

One Python process owns the web server, Reticulum stack, and all per-identity managers. The Vue frontend is static assets served from Ta5d6ff`meshchatx/public/` after a Vite build.

Ta5d6ff```

ReticulumMeshChat (meshchat.py)

|

+-- HTTP package (src/backend/http/)

| +-- middleware + register_all_routes

| +-- routes/* (/api/v1/*, shell, static helpers)

| +-- ws/* (dispatch and handlers)

+-- IdentityContext (per active identity)

| +-- SQLite via database layer

| +-- LXMRouter

| +-- TelephoneManager (LXST)

| +-- Domain managers (messages, map, docs, RRC, ...)

+-- Shared Reticulum instance (~/.reticulum by default)

```

Optional **Electron** wraps the same backend binary and loads the UI from the local HTTPS server.

Tc9d1d9## Application shell

Ta5d6ff`ReticulumMeshChat` in Ta5d6ff`meshchatx/meshchat.py` is the orchestration layer. It wires HTTP via Ta5d6ff`meshchatx/src/backend/http/`, starts and stops identity contexts, wires crash recovery, and coordinates shared process concerns. Domain to route ownership is documented in Ta5d6ff`.agents/module-ownership.md`.

Path helpers live in Ta5d6ff`meshchatx/src/path_utils.py`, Ta5d6ff`ssl_self_signed.py`, and Ta5d6ff`env_utils.py`. Ta5d6ff`meshchat.py` re-exports them for compatibility.

Tc9d1d9## Identity-scoped context

Ta5d6ff`IdentityContext` in Ta5d6ff`meshchatx/src/backend/identity_context.py` encapsulates everything tied to one cryptographic identity:

Tff7b72- Storage under Ta5d6ff`storage/identities/<identity_hash>/`

Tff7b72- Identity-local SQLite database (schema version tracked in migrations)

Tff7b72- LXMF router state and propagation directories

Tff7b72- Manager instances for messages, announces, docs, maps, forwarding, bots, RRC, Nomad page nodes, and more

Switching identities tears down the old context and loads another. Global mutable state that could leak between identities is avoided by design.

Tc9d1d9## Destination aspects

Mesh peers are addressed by destination hash plus aspect. MeshChatX currently uses:

| Aspect | Role |

| ------------------- | ---------------------------- |

| Ta5d6ff`lxmf.delivery` | LXMF mail |

| Ta5d6ff`lxmf.propagation` | Propagation node |

| Ta5d6ff`lxst.telephony` | LXST calls |

| Ta5d6ff`nomadnetwork.node` | NomadNet / Mesh Server pages |

| Ta5d6ff`rrc.hub` | Relay Chat hub |

| Ta5d6ff`map-data-v1` | Published map overlay packs |

Ta5d6ff`map-data-v1` announce app_data is a short JSON label and file count. Catalog and file bytes travel over an RNS Link, not announce payloads or LXMF. The destination is created and announced only after at least one pack is published. Mesh announce stays a separate opt-in.

Tc9d1d9## Manager-centric domain logic

Feature behaviour lives in modules under Ta5d6ff`meshchatx/src/backend/`. Examples include message handling, announce trimming, documentation, maps, page nodes, telemetry, interfaces, forwarding aliases, and RN-specific tool handlers.

Ta5d6ff`meshchat.py` should stay focused on transport and lifecycle. Business rules belong in managers where they can be unit tested.

Tc9d1d9## Persistence

Tff7b72- **Engine:** SQLite with explicit SQL and migrations (no ORM).

Tff7b72- **Schema:** Versioned migrations run during startup and identity setup.

Tff7b72- **Backups:** Automatic and manual database backups under Ta5d6ff`database-backups/`.

Tff7b72- **Recovery:** Ta5d6ff`--auto-recover`, emergency mode, and Electron crash UI can restore from backups.

Tc9d1d9## HTTP API

Routes are registered through Ta5d6ff`backend/http/register.py` into aiohttp route tables

(still discoverable as Ta5d6ff`@routes.<method>` for contract scanners). Categories include:

Tff7b72- Application status and configuration

Tff7b72- Authentication and session management

Tff7b72- LXMF messaging and conversations

Tff7b72- Telephone and voicemail

Tff7b72- Interfaces and Reticulum configuration

Tff7b72- Nomad Network and page nodes

Tff7b72- RRC client and server

Tff7b72- Tools (ping, RNPath, RNCP, RNSH, translator, bots)

Tff7b72- Map overlays and map-data-v1 publish/discover

Tff7b72- Documentation and maintenance

The frontend uses Ta5d6ff`fetch` via Ta5d6ff`apiClient.js` with CSRF tokens on mutating requests.

Tc9d1d9## WebSockets

The UI connects to Ta5d6ff`/ws` for low-latency updates. Event types include new LXMF messages, identity switches, telephone state, RRC activity, Nomad download progress, RNCP transfers, and plugin events. Handlers are registered in Ta5d6ff`wsEventRegistry.js` and dispatched through Ta5d6ff`wsEventBridge.js`.

Audio calls can use Ta5d6ff`/ws/telephone/audio` for browser-side codec bridging.

Tc9d1d9## Security model

MeshChatX defaults toward secure local operation:

Tff7b72- HTTPS and WSS enabled by default.

Tff7b72- Self-signed certificates generated per identity when custom PEM files are absent.

Tff7b72- Optional HTTP basic authentication (Ta5d6ff`--auth`).

Tff7b72- Encrypted session cookies via Ta5d6ff`aiohttp_session`.

Tff7b72- CORS, CSP, and defensive middleware on HTTP responses.

Tff7b72- Access attempt logging with lockout when auth is enabled.

The project includes extensive automated tests around auth and sessions. Even so, exposing MeshChatX directly to the public internet is not recommended without additional hardening.

Password reset is available with Ta5d6ff`--reset-password` or Ta5d6ff`MESHCHAT_RESET_PASSWORD=true`, which clears the stored bcrypt hash so you can set a new password in the UI.

Tc9d1d9## Build and packaging

One source tree produces:

Tff7b72- Development runs via Ta5d6ff`uv run python -m meshchatx.meshchat`

Tff7b72- Python wheels with bundled Ta5d6ff`public/` assets

Tff7b72- Container images (Alpine Dockerfile with standard/extra VARIANT, plus hardened Chainguard)

Tff7b72- Electron builds for Windows, macOS, and Linux

Tff7b72- Android APK via Chaquopy

Frontend build output always lands in Ta5d6ff`meshchatx/public/` so runtime behaviour matches across targets.

Tc9d1d9## Reliability features

Tff7b72- Crash recovery integration in Electron and backend startup checks

Tff7b72- Database integrity verification

Tff7b72- Backup, restore, and snapshot APIs

Tff7b72- Explicit teardown when switching identities or shutting down forwarding resources

Tff7b72- Health and status endpoints suitable for container probes

Tc9d1d9## Extensibility

MeshChatX supports plugins with separate frontend and backend runtimes:

Tff7b72- **Contribution registries** under Ta5d6ff`meshchatx/src/frontend/js/registries/` for navigation, tools, commands, settings, and WebSocket events.

Tff7b72- **Frontend plugins** run in dedicated Workers (Ta5d6ff`PluginHost.js`) with declarative UI slots.

Tff7b72- **Backend WASM plugins** run in wasmtime with fuel metering and capability-gated host functions.

Tff7b72- **Backend Python plugins** (Ta5d6ff`backend.type: "python"`) run in-process with a permission-checked host (Ta5d6ff`log`, managers, storage, network flag).

Tff7b72- **WASM bundles** embed manifest/files/signature in custom sections and unpack on install.

Tff7b72- **Sideband-compatible loader** optionally Ta5d6ff`exec`s flat Ta5d6ff`*.py` plugins with Ta5d6ff`PLUGIN_COMMAND` LXMF dispatch.

Tff7b72- **Security core** verifies RSG signatures, trusted publishers, integrity hashes, and heuristic findings.

Tff7b72- **HTTP API** under Ta5d6ff`/api/v1/plugins/*` and Ta5d6ff`/api/v1/sideband-plugins/*` for install, enable, invoke, trust, and Sideband config.

Practical extension paths today:

Tff7b72- Plugin manifests with Ta5d6ff`contributes` and Ta5d6ff`permissions` blocks

Tff7b72- New API routes and manager modules

Tff7b72- Frontend pages wired through registries

Tff7b72- New settings via Ta5d6ff`ConfigManager` and CLI or environment variables

Tff7b72- Database schema changes through migrations

Tff7b72- Generic RNS Link transport over WebSocket (Ta5d6ff`rns.link.*`) for external consoles and plugins (see [Tff7b72RNS Link API](Te6edf3rns-link-api.md))

Granted plugin manager capabilities include Ta5d6ff`destinationPath.read`, Ta5d6ff`debugLog.read`, Ta5d6ff`bugReport.*`, and Ta5d6ff`rnsLink.open` / Ta5d6ff`identify` / Ta5d6ff`request` / Ta5d6ff`send` / Ta5d6ff`close`. Hooks include Ta5d6ff`announce.received` and Ta5d6ff`rns.link.event`. Storage (Ta5d6ff`storage:isolated`) and outbound HTTP (Ta5d6ff`network:fetch`) are also grantable. The installation preview scans plugin files for external URLs and stores the user-selected grant subset.

When adding features, prefer identity-scoped state, explicit migrations, endpoint tests, and narrowly declared plugin permissions.

Tc9d1d9## NomadNet and Mesh Server

The Nomad browser and Mesh Server (page nodes) share a rendering pipeline for Micron, Markdown, plain text, and sanitised HTML. Authoring rules are documented in **NomadNet page formats**.

Tc9d1d9## Related reading

Tff7b72- **Getting started** for UI navigation and first steps.

Tff7b72- **LXMF messaging**, **Audio calls**, and **Reticulum interfaces** for feature behaviour.

Tff7b72- [Tff7b72Plugins](Te6edf3plugins.md) for extension architecture and security.

Tff7b72- The **Reticulum** tab in Documentation for protocol reference.